home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / rpm / header.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-10-22  |  20.5 KB  |  728 lines
  1. #ifndef H_HEADER
  2. #define H_HEADER
  3.  
  4. /** \ingroup header
  5.  * \file rpmdb/header.h
  6.  *
  7.  * An rpm header carries all information about a package. A header is
  8.  * a collection of data elements called tags. Each tag has a data type,
  9.  * and includes 1 or more values.
  10.  * 
  11.  * \par Historical Issues
  12.  *
  13.  * Here's a brief description of features/incompatibilities that
  14.  * have been added to headers and tags.
  15.  *
  16.  * - version 1
  17.  *    - Support for version 1 headers was removed in rpm-4.0.
  18.  *
  19.  * - version 2
  20.  *    - @todo Document version2 headers.
  21.  *
  22.  * - version 3    (added in rpm-3.0)
  23.  *    - Added RPM_I18NSTRING_TYPE as an associative array reference
  24.  *      for i18n locale dependent single element tags (i.e Group).
  25.  *    - Added an 8 byte magic string to headers in packages on-disk. The
  26.  *      magic string was not added to headers in the database.
  27.  *
  28.  * - version 4    (added in rpm-4.0)
  29.  *    - Represent file names as a (dirname/basename/dirindex) triple
  30.  *      rather than as an absolute path name. Legacy package headers are
  31.  *      converted when the header is read. Legacy database headers are
  32.  *      converted when the database is rebuilt.
  33.  *    - Simplify dependencies by eliminating the implict check on
  34.  *      package name/version/release in favor of an explict check
  35.  *      on package provides. Legacy package headers are converted
  36.  *      when the header is read. Legacy database headers are
  37.  *        converted when the database is rebuilt.
  38.  *    - (rpm-4.0.2) The original package header (and all original
  39.  *      metadata) is preserved in what's called an "immutable header region".
  40.  *      The original header can be retrieved as an RPM_BIN_TYPE, just
  41.  *      like any other tag, and the original header reconstituted using
  42.  *      headerLoad().
  43.  *    - (rpm-4.0.2) The signature tags are added (and renumbered to avoid
  44.  *      tag value collisions) to the package header during package
  45.  *      installation.
  46.  *    - (rpm-4.0.3) A SHA1 digest of the original header is appended
  47.  *      (i.e. detached digest) to the immutable header region to verify
  48.  *      changes to the original header.
  49.  *    - (rpm-4.0.3) Private methods (e.g. headerLoad(), headerUnload(), etc.)
  50.  *      to permit header data to be manipulated opaquely through vectors.
  51.  *    - (rpm-4.0.3) Sanity checks on header data to limit #tags to 65K,
  52.  *      #bytes to 16Mb, and total metadata size to 32Mb added.
  53.  *    - with addition of tracking dependencies, the package version has been
  54.  *      reverted back to 3.
  55.  * .
  56.  *
  57.  * \par Development Issues
  58.  *
  59.  * Here's a brief description of future features/incompatibilities that
  60.  * will be added to headers.
  61.  *
  62.  * - Private header methods.
  63.  *    - Private methods for the transaction element file info rpmfi may
  64.  *      be used as proof-of-concept, binary XML may be implemented
  65.  *      as a header format representation soon thereafter.
  66.  * - DSA signature for header metadata.
  67.  *    - The manner in which rpm packages are signed is going to change.
  68.  *      The SHA1 digest in the header will be signed, equivalent to a DSA
  69.  *      digital signature on the original header metadata. As the original
  70.  *      header will contain "trusted" (i.e. because the header is signed
  71.  *      with DSA) file MD5 digests, there will be little or no reason
  72.  *      to sign the payload, but that may happen as well. Note that cpio
  73.  *      headers in the payload are not used to install package metadata,
  74.  *      only the name field in the cpio header is used to associate an
  75.  *      archive file member with the corresponding entry for the file
  76.  *      in header metadata.
  77.  * .
  78.  */
  79.  
  80. /* RPM - Copyright (C) 1995-2001 Red Hat Software */
  81.  
  82. #include <stdio.h>
  83. #include "rpmio.h"
  84.  
  85. #ifdef __cplusplus
  86. extern "C" {
  87. #endif
  88.  
  89. #if 0    /* XXX hpux needs -Ae in CFLAGS to grok this */
  90. typedef long long int int_64;
  91. #endif
  92. typedef int int_32;
  93. typedef short int int_16;
  94. typedef char int_8;
  95.  
  96. #if 0    /* XXX hpux needs -Ae in CFLAGS to grok this */
  97. typedef unsigned long long int uint_64;
  98. #endif
  99. typedef unsigned int uint_32;
  100. typedef unsigned short uint_16;
  101. typedef unsigned char uint_8;
  102.  
  103. /*@-redef@*/    /* LCL: no clue */
  104. /** \ingroup header
  105.  */
  106. typedef const char *    errmsg_t;
  107.  
  108. /** \ingroup header
  109.  */
  110. typedef int_32 *    hTAG_t;
  111. typedef int_32 *    hTYP_t;
  112. typedef const void *    hPTR_t;
  113. typedef int_32 *    hCNT_t;
  114.  
  115. /** \ingroup header
  116.  */
  117. typedef /*@abstract@*/ /*@refcounted@*/ struct headerToken_s * Header;
  118.  
  119. /** \ingroup header
  120.  */
  121. typedef /*@abstract@*/ struct headerIterator_s * HeaderIterator;
  122.  
  123. /** \ingroup header
  124.  * Associate tag names with numeric values.
  125.  */
  126. typedef /*@abstract@*/ struct headerTagTableEntry_s * headerTagTableEntry;
  127. struct headerTagTableEntry_s {
  128. /*@observer@*/ /*@null@*/
  129.     const char * name;        /*!< Tag name. */
  130.     int val;            /*!< Tag numeric value. */
  131.     int type;            /*!< Tag type. */
  132. };
  133.  
  134. /** \ingroup header
  135.  */
  136. enum headerSprintfExtensionType {
  137.     HEADER_EXT_LAST = 0,    /*!< End of extension chain. */
  138.     HEADER_EXT_FORMAT,        /*!< headerTagFormatFunction() extension */
  139.     HEADER_EXT_MORE,        /*!< Chain to next table. */
  140.     HEADER_EXT_TAG        /*!< headerTagTagFunction() extension */
  141. };
  142.  
  143. /** \ingroup header
  144.  * HEADER_EXT_TAG format function prototype.
  145.  * This will only ever be passed RPM_INT32_TYPE or RPM_STRING_TYPE to
  146.  * help keep things simple.
  147.  *
  148.  * @param type        tag type
  149.  * @param data        tag value
  150.  * @param formatPrefix
  151.  * @param padding
  152.  * @param element    RPM_BIN_TYPE: no. bytes of data
  153.  * @return        formatted string
  154.  */
  155. typedef /*only@*/ char * (*headerTagFormatFunction)(int_32 type,
  156.                 const void * data, char * formatPrefix,
  157.                 int padding, int element)
  158.     /*@requires maxSet(data) >= 0 @*/;
  159.  
  160. /** \ingroup header
  161.  * HEADER_EXT_FORMAT format function prototype.
  162.  * This is allowed to fail, which indicates the tag doesn't exist.
  163.  *
  164.  * @param h        header
  165.  * @retval *type    tag type
  166.  * @retval *data    tag value
  167.  * @retval *count    no. of data items
  168.  * @retval *freedata    data-was-malloc'ed indicator
  169.  * @return        0 on success
  170.  */
  171. typedef int (*headerTagTagFunction) (Header h,
  172.         /*@null@*/ /*@out@*/ hTYP_t type,
  173.         /*@null@*/ /*@out@*/ hPTR_t * data,
  174.         /*@null@*/ /*@out@*/ hCNT_t count,
  175.         /*@null@*/ /*@out@*/ int * freeData)
  176.     /*@requires maxSet(type) >= 0 /\ maxSet(data) >= 0
  177.         /\ maxSet(count) >= 0 /\ maxSet(freeData) >= 0 @*/;
  178.  
  179. /** \ingroup header
  180.  * Define header tag output formats.
  181.  */
  182. typedef /*@abstract@*/ struct headerSprintfExtension_s * headerSprintfExtension;
  183. struct headerSprintfExtension_s {
  184.     enum headerSprintfExtensionType type;    /*!< Type of extension. */
  185. /*@observer@*/ /*@null@*/
  186.     const char * name;                /*!< Name of extension. */
  187.     union {
  188. /*@observer@*/ /*@null@*/
  189.     void * generic;                /*!< Private extension. */
  190.     headerTagFormatFunction formatFunction; /*!< HEADER_EXT_TAG extension. */
  191.     headerTagTagFunction tagFunction;    /*!< HEADER_EXT_FORMAT extension. */
  192.     struct headerSprintfExtension_s * more;    /*!< Chained table extension. */
  193.     } u;
  194. };
  195.  
  196. /** \ingroup header
  197.  * Supported default header tag output formats.
  198.  */
  199. /*@-redecl@*/
  200. /*@observer@*/
  201. extern const struct headerSprintfExtension_s headerDefaultFormats[];
  202. /*@=redecl@*/
  203.  
  204. /** \ingroup header
  205.  * Include calculation for 8 bytes of (magic, 0)?
  206.  */
  207. enum hMagic {
  208.     HEADER_MAGIC_NO        = 0,
  209.     HEADER_MAGIC_YES        = 1
  210. };
  211.  
  212. /** \ingroup header
  213.  * The basic types of data in tags from headers.
  214.  */
  215. typedef enum rpmTagType_e {
  216. #define    RPM_MIN_TYPE        0
  217.     RPM_NULL_TYPE        =  0,
  218.     RPM_CHAR_TYPE        =  1,
  219.     RPM_INT8_TYPE        =  2,
  220.     RPM_INT16_TYPE        =  3,
  221.     RPM_INT32_TYPE        =  4,
  222. /*    RPM_INT64_TYPE    = 5,   ---- These aren't supported (yet) */
  223.     RPM_STRING_TYPE        =  6,
  224.     RPM_BIN_TYPE        =  7,
  225.     RPM_STRING_ARRAY_TYPE    =  8,
  226.     RPM_I18NSTRING_TYPE        =  9
  227. #define    RPM_MAX_TYPE        9
  228. } rpmTagType;
  229.  
  230. /** \ingroup header
  231.  * New rpm data types under consideration/development.
  232.  * These data types may (or may not) be added to rpm at some point. In order
  233.  * to avoid incompatibility with legacy versions of rpm, these data (sub-)types
  234.  * are introduced into the header by overloading RPM_BIN_TYPE, with the binary
  235.  * value of the tag a 16 byte image of what should/will be in the header index,
  236.  * followed by per-tag private data.
  237.  */
  238. /*@-enummemuse -typeuse @*/
  239. typedef enum rpmSubTagType_e {
  240.     RPM_REGION_TYPE        = -10,
  241.     RPM_BIN_ARRAY_TYPE        = -11,
  242.   /*!<@todo Implement, kinda like RPM_STRING_ARRAY_TYPE for known (but variable)
  243.     length binary data. */
  244.     RPM_XREF_TYPE        = -12
  245.   /*!<@todo Implement, intent is to to carry a (???,tagNum,valNum) cross
  246.     reference to retrieve data from other tags. */
  247. } rpmSubTagType;
  248. /*@=enummemuse =typeuse @*/
  249.  
  250. /**
  251.  * Header private tags.
  252.  * @note General use tags should start at 1000 (RPM's tag space starts there).
  253.  */
  254. #define    HEADER_IMAGE        61
  255. #define    HEADER_SIGNATURES    62
  256. #define    HEADER_IMMUTABLE    63
  257. #define    HEADER_REGIONS        64
  258. #define HEADER_I18NTABLE    100
  259. #define    HEADER_SIGBASE        256
  260. #define    HEADER_TAGBASE        1000
  261.  
  262. /**
  263.  */
  264. /*@-typeuse -fielduse@*/
  265. typedef union hRET_s {
  266.     const void * ptr;
  267.     const char ** argv;
  268.     const char * str;
  269.     uint_32 * ui32p;
  270.     uint_16 * ui16p;
  271.     int_32 * i32p;
  272.     int_16 * i16p;
  273.     int_8 * i8p;
  274. } * hRET_t;
  275. /*@=typeuse =fielduse@*/
  276.  
  277. /**
  278.  */
  279. /*@-typeuse -fielduse@*/
  280. typedef struct HE_s {
  281.     int_32 tag;
  282. /*@null@*/
  283.     hTYP_t typ;
  284.     union {
  285. /*@null@*/
  286.     hPTR_t * ptr;
  287. /*@null@*/
  288.     hRET_t * ret;
  289.     } u;
  290. /*@null@*/
  291.     hCNT_t cnt;
  292. } * HE_t;
  293. /*@=typeuse =fielduse@*/
  294.  
  295. /** \ingroup header
  296.  * Create new (empty) header instance.
  297.  * @return        header
  298.  */
  299. typedef
  300. Header (*HDRnew) (void)
  301.     /*@*/;
  302.  
  303. /** \ingroup header
  304.  * Dereference a header instance.
  305.  * @param h        header
  306.  * @return        NULL always
  307.  */
  308. typedef
  309. /*@null@*/ Header (*HDRfree) (/*@killref@*/ /*@null@*/ Header h)
  310.         /*@modifies h @*/;
  311.  
  312. /** \ingroup header
  313.  * Reference a header instance.
  314.  * @param h        header
  315.  * @return        referenced header instance
  316.  */
  317. typedef
  318. Header (*HDRlink) (Header h)
  319.         /*@modifies h @*/;
  320.  
  321. /** \ingroup header
  322.  * Dereference a header instance.
  323.  * @param h        header
  324.  * @return        NULL always
  325.  */
  326. typedef
  327. Header (*HDRunlink) (/*@killref@*/ /*@null@*/ Header h)
  328.         /*@modifies h @*/;
  329.  
  330. /** \ingroup header
  331.  * Sort tags in header.
  332.  * @todo Eliminate from API.
  333.  * @param h        header
  334.  */
  335. typedef
  336. void (*HDRsort) (Header h)
  337.         /*@modifies h @*/;
  338.  
  339. /** \ingroup header
  340.  * Restore tags in header to original ordering.
  341.  * @todo Eliminate from API.
  342.  * @param h        header
  343.  */
  344. typedef
  345. void (*HDRunsort) (Header h)
  346.         /*@modifies h @*/;
  347.  
  348. /** \ingroup header
  349.  * Return size of on-disk header representation in bytes.
  350.  * @param h        header
  351.  * @param magicp    include size of 8 bytes for (magic, 0)?
  352.  * @return        size of on-disk header
  353.  */
  354. typedef
  355. unsigned int (*HDRsizeof) (/*@null@*/ Header h, enum hMagic magicp)
  356.         /*@modifies h @*/;
  357.  
  358. /** \ingroup header
  359.  * Convert header to on-disk representation.
  360.  * @param h        header (with pointers)
  361.  * @return        on-disk header blob (i.e. with offsets)
  362.  */
  363. typedef
  364. /*@only@*/ /*@null@*/ void * (*HDRunload) (Header h)
  365.         /*@modifies h @*/;
  366.  
  367. /** \ingroup header
  368.  * Convert header to on-disk representation, and then reload.
  369.  * This is used to insure that all header data is in one chunk.
  370.  * @param h        header (with pointers)
  371.  * @param tag        region tag
  372.  * @return        on-disk header (with offsets)
  373.  */
  374. typedef
  375. /*@null@*/ Header (*HDRreload) (/*@only@*/ Header h, int tag)
  376.         /*@modifies h @*/;
  377.  
  378. /** \ingroup header
  379.  * Duplicate a header.
  380.  * @param h        header
  381.  * @return        new header instance
  382.  */
  383. typedef
  384. Header (*HDRcopy) (Header h)
  385.         /*@modifies h @*/;
  386.  
  387. /** \ingroup header
  388.  * Convert header to in-memory representation.
  389.  * @param uh        on-disk header blob (i.e. with offsets)
  390.  * @return        header
  391.  */
  392. typedef
  393. /*@null@*/ Header (*HDRload) (/*@kept@*/ void * uh)
  394.     /*@modifies uh @*/;
  395.  
  396. /** \ingroup header
  397.  * Make a copy and convert header to in-memory representation.
  398.  * @param uh        on-disk header blob (i.e. with offsets)
  399.  * @return        header
  400.  */
  401. typedef
  402. /*@null@*/ Header (*HDRcopyload) (const void * uh)
  403.     /*@*/;
  404.  
  405. /** \ingroup header
  406.  * Read (and load) header from file handle.
  407.  * @param fd        file handle
  408.  * @param magicp    read (and verify) 8 bytes of (magic, 0)?
  409.  * @return        header (or NULL on error)
  410.  */
  411. typedef
  412. /*@null@*/ Header (*HDRread) (FD_t fd, enum hMagic magicp)
  413.     /*@modifies fd @*/;
  414.  
  415. /** \ingroup header
  416.  * Write (with unload) header to file handle.
  417.  * @param fd        file handle
  418.  * @param h        header
  419.  * @param magicp    prefix write with 8 bytes of (magic, 0)?
  420.  * @return        0 on success, 1 on error
  421.  */
  422. typedef
  423. int (*HDRwrite) (FD_t fd, /*@null@*/ Header h, enum hMagic magicp)
  424.     /*@globals fileSystem @*/
  425.     /*@modifies fd, h, fileSystem @*/;
  426.  
  427. /** \ingroup header
  428.  * Check if tag is in header.
  429.  * @param h        header
  430.  * @param tag        tag
  431.  * @return        1 on success, 0 on failure
  432.  */
  433. typedef
  434. int (*HDRisentry) (/*@null@*/Header h, int_32 tag)
  435.         /*@*/;  
  436.  
  437. /** \ingroup header
  438.  * Free data allocated when retrieved from header.
  439.  * @param h        header
  440.  * @param data        address of data (or NULL)
  441.  * @param type        type of data (or -1 to force free)
  442.  * @return        NULL always
  443.  */
  444. typedef
  445. /*@null@*/ void * (*HDRfreetag) (Header h,
  446.         /*@only@*/ /*@null@*/ const void * data, rpmTagType type)
  447.     /*@modifies data @*/;
  448.  
  449. /** \ingroup header
  450.  * Retrieve tag value.
  451.  * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
  452.  * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
  453.  * entry is present).
  454.  *
  455.  * @param h        header
  456.  * @param tag        tag
  457.  * @retval type        address of tag value data type (or NULL)
  458.  * @retval p        address of pointer to tag value(s) (or NULL)
  459.  * @retval c        address of number of values (or NULL)
  460.  * @return        1 on success, 0 on failure
  461.  */
  462. typedef
  463. int (*HDRget) (Header h, int_32 tag,
  464.             /*@null@*/ /*@out@*/ hTYP_t type,
  465.             /*@null@*/ /*@out@*/ void ** p,
  466.             /*@null@*/ /*@out@*/ hCNT_t c)
  467.     /*@modifies *type, *p, *c @*/;
  468.  
  469. /** \ingroup header
  470.  * Retrieve tag value using header internal array.
  471.  * Get an entry using as little extra RAM as possible to return the tag value.
  472.  * This is only an issue for RPM_STRING_ARRAY_TYPE.
  473.  *
  474.  * @param h        header
  475.  * @param tag        tag
  476.  * @retval type        address of tag value data type (or NULL)
  477.  * @retval p        address of pointer to tag value(s) (or NULL)
  478.  * @retval c        address of number of values (or NULL)
  479.  * @return        1 on success, 0 on failure
  480.  */
  481. typedef
  482. int (*HDRgetmin) (Header h, int_32 tag,
  483.             /*@null@*/ /*@out@*/ hTYP_t type,
  484.             /*@null@*/ /*@out@*/ hPTR_t * p,
  485.             /*@null@*/ /*@out@*/ hCNT_t c)
  486.     /*@modifies *type, *p, *c @*/;
  487.  
  488. /** \ingroup header
  489.  * Add tag to header.
  490.  * Duplicate tags are okay, but only defined for iteration (with the
  491.  * exceptions noted below). While you are allowed to add i18n string
  492.  * arrays through this function, you probably don't mean to. See
  493.  * headerAddI18NString() instead.
  494.  *
  495.  * @param h        header
  496.  * @param tag        tag
  497.  * @param type        tag value data type
  498.  * @param p        pointer to tag value(s)
  499.  * @param c        number of values
  500.  * @return        1 on success, 0 on failure
  501.  */
  502. typedef
  503. int (*HDRadd) (Header h, int_32 tag, int_32 type, const void * p, int_32 c)
  504.         /*@modifies h @*/;
  505.  
  506. /** \ingroup header
  507.  * Append element to tag array in header.
  508.  * Appends item p to entry w/ tag and type as passed. Won't work on
  509.  * RPM_STRING_TYPE. Any pointers into header memory returned from
  510.  * headerGetEntryMinMemory() for this entry are invalid after this
  511.  * call has been made!
  512.  *
  513.  * @param h        header
  514.  * @param tag        tag
  515.  * @param type        tag value data type
  516.  * @param p        pointer to tag value(s)
  517.  * @param c        number of values
  518.  * @return        1 on success, 0 on failure
  519.  */
  520. typedef
  521. int (*HDRappend) (Header h, int_32 tag, int_32 type, const void * p, int_32 c)
  522.         /*@modifies h @*/;
  523.  
  524. /** \ingroup header
  525.  * Add or append element to tag array in header.
  526.  * @todo Arg "p" should have const.
  527.  * @param h        header
  528.  * @param tag        tag
  529.  * @param type        tag value data type
  530.  * @param p        pointer to tag value(s)
  531.  * @param c        number of values
  532.  * @return        1 on success, 0 on failure
  533.  */
  534. typedef
  535. int (*HDRaddorappend) (Header h, int_32 tag, int_32 type, const void * p, int_32 c)
  536.         /*@modifies h @*/;
  537.  
  538. /** \ingroup header
  539.  * Add locale specific tag to header.
  540.  * A NULL lang is interpreted as the C locale. Here are the rules:
  541.  * \verbatim
  542.  *    - If the tag isn't in the header, it's added with the passed string
  543.  *       as new value.
  544.  *    - If the tag occurs multiple times in entry, which tag is affected
  545.  *       by the operation is undefined.
  546.  *    - If the tag is in the header w/ this language, the entry is
  547.  *       *replaced* (like headerModifyEntry()).
  548.  * \endverbatim
  549.  * This function is intended to just "do the right thing". If you need
  550.  * more fine grained control use headerAddEntry() and headerModifyEntry().
  551.  *
  552.  * @param h        header
  553.  * @param tag        tag
  554.  * @param string    tag value
  555.  * @param lang        locale
  556.  * @return        1 on success, 0 on failure
  557.  */
  558. typedef
  559. int (*HDRaddi18n) (Header h, int_32 tag, const char * string,
  560.                 const char * lang)
  561.         /*@modifies h @*/;
  562.  
  563. /** \ingroup header
  564.  * Modify tag in header.
  565.  * If there are multiple entries with this tag, the first one gets replaced.
  566.  * @param h        header
  567.  * @param tag        tag
  568.  * @param type        tag value data type
  569.  * @param p        pointer to tag value(s)
  570.  * @param c        number of values
  571.  * @return        1 on success, 0 on failure
  572.  */
  573. typedef
  574. int (*HDRmodify) (Header h, int_32 tag, int_32 type, const void * p, int_32 c)
  575.         /*@modifies h @*/;
  576.  
  577. /** \ingroup header
  578.  * Delete tag in header.
  579.  * Removes all entries of type tag from the header, returns 1 if none were
  580.  * found.
  581.  *
  582.  * @param h        header
  583.  * @param tag        tag
  584.  * @return        0 on success, 1 on failure (INCONSISTENT)
  585.  */
  586. typedef
  587. int (*HDRremove) (Header h, int_32 tag)
  588.         /*@modifies h @*/;
  589.  
  590. /** \ingroup header
  591.  * Return formatted output string from header tags.
  592.  * The returned string must be free()d.
  593.  *
  594.  * @param h        header
  595.  * @param fmt        format to use
  596.  * @param tags        array of tag name/value pairs
  597.  * @param extensions    chained table of formatting extensions.
  598.  * @retval errmsg    error message (if any)
  599.  * @return        formatted output string (malloc'ed)
  600.  */
  601. typedef
  602. /*@only@*/ char * (*HDRsprintf) (Header h, const char * fmt,
  603.              const struct headerTagTableEntry_s * tags,
  604.              const struct headerSprintfExtension_s * extensions,
  605.              /*@null@*/ /*@out@*/ errmsg_t * errmsg)
  606.     /*@modifies *errmsg @*/;
  607.  
  608. /** \ingroup header
  609.  * Duplicate tag values from one header into another.
  610.  * @param headerFrom    source header
  611.  * @param headerTo    destination header
  612.  * @param tagstocopy    array of tags that are copied
  613.  */
  614. typedef
  615. void (*HDRcopytags) (Header headerFrom, Header headerTo, hTAG_t tagstocopy)
  616.     /*@modifies headerFrom, headerTo @*/;
  617.  
  618. /** \ingroup header
  619.  * Destroy header tag iterator.
  620.  * @param hi        header tag iterator
  621.  * @return        NULL always
  622.  */
  623. typedef
  624. HeaderIterator (*HDRfreeiter) (/*@only@*/ HeaderIterator hi)
  625.     /*@modifies hi @*/;
  626.  
  627. /** \ingroup header
  628.  * Create header tag iterator.
  629.  * @param h        header
  630.  * @return        header tag iterator
  631.  */
  632. typedef
  633. HeaderIterator (*HDRinititer) (Header h)
  634.     /*@modifies h */;
  635.  
  636. /** \ingroup header
  637.  * Return next tag from header.
  638.  * @param hi        header tag iterator
  639.  * @retval tag        address of tag
  640.  * @retval type        address of tag value data type
  641.  * @retval p        address of pointer to tag value(s)
  642.  * @retval c        address of number of values
  643.  * @return        1 on success, 0 on failure
  644.  */
  645. typedef
  646. int (*HDRnextiter) (HeaderIterator hi,
  647.         /*@null@*/ /*@out@*/ hTAG_t tag,
  648.         /*@null@*/ /*@out@*/ hTYP_t type,
  649.         /*@null@*/ /*@out@*/ hPTR_t * p,
  650.         /*@null@*/ /*@out@*/ hCNT_t c)
  651.     /*@modifies hi, *tag, *type, *p, *c @*/;
  652.  
  653. /** \ingroup header
  654.  * Header method vectors.
  655.  */
  656. typedef /*@abstract@*/ struct HV_s * HV_t;
  657. struct HV_s {
  658.     HDRlink    hdrlink;
  659.     HDRunlink    hdrunlink;
  660.     HDRfree    hdrfree;
  661.     HDRnew    hdrnew;
  662.     HDRsort    hdrsort;
  663.     HDRunsort    hdrunsort;
  664.     HDRsizeof    hdrsizeof;
  665.     HDRunload    hdrunload;
  666.     HDRreload    hdrreload;
  667.     HDRcopy    hdrcopy;
  668.     HDRload    hdrload;
  669.     HDRcopyload    hdrcopyload;
  670.     HDRread    hdrread;
  671.     HDRwrite    hdrwrite;
  672.     HDRisentry    hdrisentry;
  673.     HDRfreetag    hdrfreetag;
  674.     HDRget    hdrget;
  675.     HDRgetmin    hdrgetmin;
  676.     HDRadd    hdradd;
  677.     HDRappend    hdrappend;
  678.     HDRaddorappend hdraddorappend;
  679.     HDRaddi18n    hdraddi18n;
  680.     HDRmodify    hdrmodify;
  681.     HDRremove    hdrremove;
  682.     HDRsprintf    hdrsprintf;
  683.     HDRcopytags    hdrcopytags;
  684.     HDRfreeiter    hdrfreeiter;
  685.     HDRinititer    hdrinititer;
  686.     HDRnextiter    hdrnextiter;
  687. /*@null@*/
  688.     void *    hdrvecs;
  689. /*@null@*/
  690.     void *    hdrdata;
  691.     int        hdrversion;
  692. };
  693.  
  694. /** \ingroup header
  695.  * Free data allocated when retrieved from header.
  696.  * @deprecated Use headerFreeTag() instead.
  697.  * @todo Remove from API.
  698.  *
  699.  * @param data        address of data (or NULL)
  700.  * @param type        type of data (or -1 to force free)
  701.  * @return        NULL always
  702.  */
  703. /*@unused@*/ static inline /*@null@*/
  704. void * headerFreeData( /*@only@*/ /*@null@*/ const void * data, rpmTagType type)
  705.     /*@modifies data @*/
  706. {
  707.     if (data) {
  708.     /*@-branchstate@*/
  709.     if (type == -1 ||
  710.         type == RPM_STRING_ARRAY_TYPE ||
  711.         type == RPM_I18NSTRING_TYPE ||
  712.         type == RPM_BIN_TYPE)
  713.         free((void *)data);
  714.     /*@=branchstate@*/
  715.     }
  716.     return NULL;
  717. }
  718.  
  719. #if !defined(__HEADER_PROTOTYPES__)
  720. #include "hdrinline.h"
  721. #endif
  722.  
  723. #ifdef __cplusplus
  724. }
  725. #endif
  726.  
  727. #endif    /* H_HEADER */
  728.